Kurze Beschreibung der Modulschnittstelle fr CAB.APP (bzw. HTML.APP). ---------------------------------------------------------------------- Kontakt ------- Alexander Clauss Stresemannstr. 44 D-64297 Darmstadt email: aclauss@rbg.informatik.th-darmstadt.de Hinweise -------- Das Programm CAB.APP besitzt keine Routinen um online auf das Internet (bzw. das WWW) zuzugreifen. Der Grund ist: ich habe kein Modem und k”nnte diese Routinen deshalb auch nicht testen. šber ein externes Modul (CAB.OVL) k”nnen diese Routinen aber nachgerstet werden. Die Schnittstelle soll auch unter Single-TOS funktionieren, daher werden keine speziellen Mint-Features verwendet. Sollte sie fr bestimmte Module unbrauchbar sein, bitte ich um Nachricht. Die Schnittstelle kann an einigen Stellen noch erweitert und verbessert werden. Sie enth„lt wahrscheinlich auch ein paar berflssige Aufrufe, die zwar in irgendwelchen Alpha-Version eines Moduls benutzt wurden, aber jetzt h”chst wahrscheinlich niemand mehr benutzen wird (z.B. begin_pexec(), end_pexec() wurden ben”tigt, weil fr die ersten Versuche ein ZMODEM Programm gestartet wurde, um Daten zu bertragen). Vorschl„ge zur Verbesserung bzw. Erweiterung der Modul-Schnittstelle werden gerne entgegengenommen. Aufruf des Moduls ----------------- Es gibt (zur Zeit) zwei M”glichkeiten: 1) CAB.APP l„d das Modul CAB.OVL mit pexec(3,...). Das Modul wird dadurch in den Speicher geladen und reloziert, aber nicht gestartet. Nun sucht CAB.APP nach einer 'magic number' im Speicherbereich des Moduls. Direkt hinter dieser Zahl erwartet es die Adresse der Initialisierungs-Routine des Moduls. Nun springt es diese Funktion an und bergibt die Adressen zweier Strukturen. Eine dieser Strukturen enth„lt Funktionen, die CAB.APP zur Verfgung stellt, und die vom Modul verwendet werden k”nnen. Die andere Struktur muž von der Initialisierungs-Funktion des Moduls ausgefllt werden, diese muž dort die Adressen der Modul-Funktionen eintragen damit sie von CAB.APP aufgerufen werden k”nnen. Die 'magic number' ist: 0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536552 CAP.APP gibt dabei nach dem Laden des Moduls mit mshrink() den vom Modul nicht ben”tigten Speicher frei. Muss das Modul diesen mshrink() Aufruf selbst durchfhren, dann muž die 'magic number' flgendermažen lauten: 0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536572 Nachteil dieser Methode: Der Startupcode des Moduls wird nicht ausgefhrt (und deshalb sind alle Aufrufe von Funktionen die im Startupcode initialisiert werden, nicht m”glich (betrifft z.B. printf()). 2) Als Alternative ist es auch m”glich, daž ein Programm, welches die Funktionen des Moduls bereitstellt, CAB.APP selbst nachstartet. In diesem Fall muž CAB.APP mit dem Parameter -initfunc= in der Kommandozeile aufgerufen werden. steht dabei fr die Adresse der init-Funktion (in dezimaler Darstellung, also nicht(!) Hexadezimal). Die 'Magic Number' wird in diesem Falle nicht ben”tigt. Unter Mint mit Memory-Protection muž man dann die Memory-Flags auf GLOBAL setzen (bei beiden Programmen), da beide Programme Routinen des jeweils anderen aufrufen. Aufrufkonventionen ------------------ Alle Funktionsparameter mssen auf dem Stack bergeben werden. Das Ergebnis wird im Register D0 bergeben. Variablem vom Typ 'long' sind 32 Bit breit, vom Typ 'int' 16 Bit. Bit 0 bezeichnet das niederwertigste Bit Das bedeutet fr Pure C: Alle Funktionen mit 'cdecl' deklarieren Das bedeutet fr den gcc: Die Option '-mshort' verwenden. Beschreibung der Funktionen des Moduls -------------------------------------- In 'modul.h' und 'init.c' (zusammengestellt von Stephane Boisson) befindet sich schon ein Grundgerst eines Moduls. Fr Aufrufmethode 1) muž man in main() (welches nie ausgefhrt wird) einige Dummy-Aufrufe machen, damit der Compiler nicht alle Funktionen wegoptimiert. long init_module(url_methods_t *out, browser_info_t *in, char *path); --------------------------------------------------------------------- Diese Funktion ruft CAB.APP direkt nach dem Start auf. In dieser Funktion muž sich das Modul initialisieren. 'path' enth„lt den Pfad in dem sich das Modul befindet (abgeschlossen durch '\'). 'in' enth„lt alle Funktionen, die CAB-APP dem Modul zur Verfgung stellt. 'out' In diese Struktur mssen die Adressen der Modul- Funktionen eingetragen werden. Fr Funktionen, die nicht implementiert sind, setzt man 0L als Adresse ein. Als Ergebnis muž die Funktion einen Bitvektor (long) zurckliefern, indem die vom Modul untersttzten WWW-Protokolle eingetragen wurden. Konstanten fr die Protokolle (mit 'Oder' zu veknpfen): SUPPORT_HTTP, SUPPORT_FTP, SUPPORT_GOPHER, SUPPORT_WAIS, SUPPORT_MAILTO, SUPPORT_NNTP, SUPPORT_TELNET Falls das Modul weitere Programme mit pexec(0) startet, muž man zus„tzlich noch folgendes in den Bitvektor eintragen: SUPPORT_PEXEC Falls die Initialisierung nicht klappt muž 0L zurck geliefert werden; weitere Aufrufe von Modul-Funktionen finden dann nicht mehr statt. Wichtig fr Aufrufmethode 1 (siehe oben): Die Adresse dieser Funktion muž direkt hinter der 'Magic number' irgendwo im Programm- oder Datenbereich untergebracht werden, damit CAB.APP diese Funktion findet und aufrufen kann (gilt nur wenn das Modul mit pexec(3) von CAB.APP geladen wurde). Wichtig fr Aufrufmethode 2 (siehe oben): Das Modul wird als Programm gestartet, und startet dann selbst CAB.APP, wobei es die Adresse dieser Funktion als Parameter bergibt: Parameter: -initfunc= void restore_module(void); -------------------------- Wird aufgerufen, bevor sich CAB.APP beendet. Die Funktion sollte hier allen angeforderten Speicher freigeben, ge”ffnete Datein schliessen, etc. Diese Funktion muž nicht implementiert werden, wenn nichts dauerhaft reserviert wurde (Dateihandles, Speicher, etc.) void get_version(char **authorp, long *versionp, long *datep); -------------------------------------------------------------- Erfragt Informationen ber Autor, Version und Datum des Moduls. Alle Angaben werden im 'About...' Dialog von CAB.APP angezeigt. 'authorp' Autor und Kontaktadresse. Maximal 4 Zeilen zu je 30 Zeichen. Als Zeilentrenner bitte '|' verwenden. 'versionp' Version im BCD-Format. Oberes Wort enth„lt die Haupt- versionsnummer, das untere Wort die Unterversionsnummer. 'datep' Datum im BCD-Format: 0xYYYYMMDD (Jahr, Monat, Tag) Diese Funktion muž nicht implementiert werden. long get_url_info(char *url, long *timep, long *sizep, char *type); ------------------------------------------------------------------- šber das Dokument mit der URL-Adresse 'url' sollen einige Informationen ermittelt werden. Diese Funktion wird aufgerufen um zu entscheiden, ob ein Dokument berhaupt aus dem Internet angefordert werden muž, oder ob das Dokument im Cache noch aktuell ist. 'url' URL-Adresse des Dokuments, ber das Informationen gefordert werden. 'timep' Hier muž das Datum (letzte Modifikation) eingetragen werden. Im UNIX-Format: Sekunden seit 1970 (01.01.1970,00:00 => *timep=0) 'sizep' Hier soll die L„nge (in bytes) des Dokuments eingetragen werden. -1L wenn nicht feststellbar. 'type' Der Dateityp im MIME-Format. Der String-Puffer bietet Platz fr 250 Zeichen. Oder Leerstring '\0', falls unbekannt. Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer. Diese Funktion muž nicht implementiert werden. Ist fr optimale Cache- Verwaltung aber sinnvoll. long get_url(char *url, char *filename); ---------------------------------------- Das Modul soll das Dokument mit der URL-Adresse 'url' aus dem Internet holen und in der Datei 'filename' speichern. 'filename' enth„lt schon den kompletten Zugriffspfad; Verzeichnisse mssen nicht mehr angelegt werden. Das Dateidatum sollte korrekt auf das Datum der letzten Modifikation des Dokuments gesetzt werden. Nur so funktioniert die Cache-Verwaltung in Verbindung mit der 'get_url_info(..)' Funktion. Sollte das Ziel der URL-Adresse ein Verzeichnis sein (z.B. beim ftp, gopher Protokoll) sollte das Ergebnis als HTML-Datei abgelegt werden (falls das nicht schon automatisch im HTML-Format ankommt???). Wenn man die Verzeichniseintr„ge mit Icons versieht, kann man die folgenden eingebauten Icons benutzen: #define BULLET_FOLDER "" #define BULLET_TEXT "" #define BULLET_IMAGE "" #define BULLET_MOVIE "" #define BULLET_SOUND "" #define BULLET_INDEX "" #define BULLET_BINARY "" #define BULLET_UNKNOW "" Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer. Wird die URL-Adresse umgeleitet (Image-Maps,...) muss man dies CAB.APP mit der Funktion 'new_url' (siehe unten) mitteilen. long post(char *url,char *content, char *enctype, char *filename); ------------------------------------------------------------------ Die Daten ('content') einer FORM-Umgebung werden mit 'POST' an 'url' geschickt. Die Daten liegen im 'enctype' (MIME) Format vor. Zur Zeit ist nur 'application/x-www-form-urlencoded' m”glich. Eventuell zurckgeschickte Daten sollen in 'filename' gespeichert werden. Sollten die zurckgeschickten Datein eine neue URL-Adresse besitzen, dann unbedingt die Funktion 'new_url' (siehe unten) benutzen. long mailto(char *url, char *subject, char *filename); ------------------------------------------------------ Die Datei 'filename' soll als Mail verschickt werden. 'url' bezeichnet die Email-Adresse des Empf„ngers als URL, 'subject' ist der Betreff. Als Ergebnis liefert die Funtkion 0, falls alles geklappt hat, sonst -1. Funktionen, die CAB.APP anbietet (browser_info_t Struktur) ---------------------------------------------------------- Das Modul kann direkt AES-Aufrufe machen, im Allgemeinen ist das aber nicht n”tig. void (*aes_crystal)(void) ------------------------- Fr AES-Aufrufe bitte die folgenden Arrays ausfllen und dann 'aes_crystal' aufrufen. int *aes_control; int *aes_global; int *aes_intin; int *aes_intout; long *aes_addrin; long *aes_addrout; void (*aes_messages)(int *msg) ------------------------------ Besitzt das Modul eine eigene AES-Event-Behandlung, sollte bei jedem MU_MESAG-Event (bzw. jedem Event, welches nicht das Modul betrifft) der Ereignis-Puffer mit dieser Funktion an CAB.APP weitergereicht werden, damit dieses z.B. Redraws ausfhren kann. void (*msg_error)(long errno) ----------------------------- Gibt eine Fehlermeldung aus (im Statusfenster von CAB.APP). Erlaubt sind alle GEMDOS, BIOS und MintNet Fehlernummern. void (*msg_status)(long no,long val) ------------------------------------ Gibt eine der folgenden Statusmeldngen aus: no=1: 'connecting host', val unbenutzt no=2: 'receive data', val=Anzahl der empfangenen Bytes no=3: 'waiting for response', val unbenutzt no=4: 'resolving host', val unbenutzt no=5: 'sending request', val unbenutzt no=6: 'Text formatieren...', val unbenutzt no=7: 'Bild laden...', val unbenutzt no=8: 'Starte Programm...', val unbenutzt no=9: 'Formatiere Tabelle...', val unbenutzt no=10: 'Warte auf Daten (Timeout: #)', val=Timeout no=11: 'Konvertiere Bild...', val unbenutzt Weitere Meldungen k”nnen bei Bedarf aufgenommen werden. Nummern bitte mit mir absprechen. long (*aes_events)(long msec) ----------------------------- Mit dieser Funktion gibt man CAB.APP die Gelegenheit auf AES-Ereignisse zu reagieren. CAB.APP ruft evnt_multi(MU_MESAG|MU_TIMER|MU_KEYBD,..) auf, wobei 'msec' als Zeit fr das Timer-Event benutzt wird. Mit einem kleinen Wert fr 'msec' kehrt die Funktion also schnell wieder zurck. CAB.APP ver- arbeitet zun„chst alle eigenen Events (z.B. Redraw, Fenster verschieben,..) und prft, ob der Benutzer die Aktion abbrechen will. Als Ergebnis liefert die Funktion: 0 -> kein MU_MESAG-Event. Weitermachen. -1 -> Aktion abbrechen (Benutzer hat ESC gedrckt). alles andere -> Pointer auf ein GEM-Message-Array (int msg[8]) mit den Daten des aktuellen MU_MESAG-Ereignises. long (*alert_box)(long button,long msg) --------------------------------------- Eine Alertbox wird dargestellt. 'button' ist der Default-Button und 'msg' die Nummer eines Textes. Die Funktion liefert 0, wenn ein Fehler auftrat (falsche msg Nummer), sonst den ausgew„hlten Button. M”gliche Texte (msg): msg=0 : "[2][Aktion abbrechen?][Ja|Nein]" msg=1 : "[1][Transaktion war erfolgreich][Abbruch]" msg=2 : "[1][Transaktion war nicht|erfolgreich][Abbruch]" Weitere Texte k”nnen bei Bedarf aufgenommen werden. Nummer bitte mit mir absprechen. void (*begin_pexec)(void) void (*end_pexec)(void) ---------------------------------------------------- Mit diesen beiden Funktionen muž das Starten eines Programmes durch pexec(0) geklammert werden. CAB.APP wird sich unter Single-TOS beim AES korrekt ab- und danach wieder anmelden. int (*clear_cache)(long size) ----------------------------- Sorgt dafr, daž mindestens 'size' Bytes im Cache frei sind. Gegebenenfalls werden einige Dateien (auf die am l„ngsten nicht mehr zugegriffen wurde) aus dem Cache entfernt. Konnte soviel Platz geschaffen werden, liefert die Funktion 0 sonst -1. size=0 bedeutet, daž der komplette Cache gel”scht wird. int (*new_url)(char *url,char **file) ------------------------------------- Wenn eine Dokument-Anfrage auf eine neue URL-Adresse umgeleitet wird (z.B. Imagemaps, cgi-Scripts), muž man dies dem Hautprogramm mit dieser Funktion mitteilen. Es ermittelt dann einen neuen Dateinamen 'file', unter dem die Daten dann abgespeichert werden mssen. Liefert die Funktion als Ergebnis 0 soll das Dokument jetzt endgltig geholt werden, liefert sie als Ergebnis -1, dann muž das Dokument nicht mehr geholt werden, da es sich schon im Cache befindet. int (*ask_user)(long msg,char **answer) --------------------------------------- Wenn der Benutzter bestimmte Angaben machen muž, bevor fortgefahren werden kann (z.B. bei geschtzten Dokumenten mit Passwortabfrage), kann man diese Angaben hiermit anfordern. 'msg' ist die Nummer des Textes, der angezeigt wird, 'answer' ist der String, der vom Benutzer eingegeben wurde. Das Resultat ist 1 wenn der Benutzter OK gedrckt hat, 0 fr Abbruch und -1 bei einem Fehler (falsche 'msg'-Nummer). Der String 'answer' wird beim n„chsten Aufruf dieser Funktion wieder berschrieben daher, wenn n”tig, umkopieren. M”glicher Werte fr 'msg': msg=0 : Dokument geschtzt, Name (bzw. Kennung) eingeben msg=1 : Dokument geschtzt, Passwort eingeben Weitere Texte k”nnen bei Bedarf definiert werden. Bitte mit mir absprechen. long basepage ------------- Adresse der Modul-Basepage. Nur gltig, wenn Modul mit pexec(3) gestartet wurde. int *reloadflag --------------- Zeiger auf ein integer. Der Integerwert ist 1, wenn der Benutzer 'Neu laden' (Reload) ausgew„hlt hat, sonst 0. Kann dazu verwendet werden, eventuell gecachete Informationen/Daten zu benutzen oder nicht. long version ------------ Versionsnummer von CAB im ASCII format. Beispiel: V1.30 w„re 0x30313330. proxy_url *proxy ---------------- Zeiger auf die folgende Struktur: struct { char *ftp_proxy; char *http_proxy; char *wais_proxy; char *gopher_proxy; char *news_proxy; char *no_proxy; char *smtp_server; char *nntp_server; } proxy_url Das OVL sollte diese Struktur innerhalb der init-Funktion mit Default-Werten ausfuellen. CAB hat fuer jeden String schon Speicher (126 Bytes) reserviert. CAB wird diese Eintr„ge „ndern, falls der Benutzter neue Eintr„ge in CAB bestimmt. Das OVL sollte deshalb vor dem Download der Daten diese Eintr„ge benutzten. void online(int state) ---------------------- Sollte vom OVL immer dann aufgerufen werden, wenn die Internet- verbindung aufgebaut bzw. abgebrochen wird. Besteht die Verbindung muž state=1 sonst state=0 bergeben werden. Diese Funktion darf ab CAB-Version 1.41 aufgerufen werden (d.h.: version>=0x30313431). Wird diese Funktion vom OVL nicht aufgerufen, geht CAB davon aus, daž die Internetverbindung besteht.